<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
How do I use eclipse?
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot012.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot008.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot014.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc20">3.5</A>&nbsp;&nbsp;How do I use <TT>eclipse</TT>?</H2><UL>
<LI><A HREF="umsroot013.html#toc9">Getting started</A>
<LI><A HREF="umsroot013.html#toc10">Interacting with the top level loop</A>
<LI><A HREF="umsroot013.html#toc11">Compiling a program</A>
<LI><A HREF="umsroot013.html#toc12">Entering a program from the terminal</A>
<LI><A HREF="umsroot013.html#toc13">Executing a query</A>
<LI><A HREF="umsroot013.html#toc14">Interrupting the execution</A>
<LI><A HREF="umsroot013.html#toc15">Debugging a program</A>
<LI><A HREF="umsroot013.html#toc16">The history mechanism</A>
<LI><A HREF="umsroot013.html#toc17">Getting help</A>
</UL>


<A NAME="toc9"></A>
<H3 CLASS="subsection"><A NAME="htoc21">3.5.1</A>&nbsp;&nbsp;Getting started</H3>
To start ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, type the command <TT>eclipse</TT> at an
operating system command-line prompt.
This will display something like this:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
% eclipse
ECLiPSe Constraint Logic Programming System [kernel]
Kernel and basic libraries copyright Cisco Systems, Inc.
and subject to the Cisco-style Mozilla Public Licence 1.1
(see legal/cmpl.txt or www.eclipse-clp.org/licence)
Source available at www.sourceforge.org/projects/eclipse-clp
GMP library copyright Free Software Foundation, see legal/lgpl.txt
For other libraries see their individual copyright notices
Version X.Y #Z, DAY MONTH DD HH:MM YYYY
[eclipse 1]:
</PRE></BLOCKQUOTE>
The list in square brackets on the first line specifies the configuration
of the running system, i.e., the language extensions that are present.
The copyright and version information is followed by the prompt
<TT>[eclipse 1]:</TT>, which tells the user that the top-level loop is waiting
for a user query in the module <TT>eclipse</TT>.
The predicate <B>help/0</B><A NAME="@default95"></A> gives
general help and <A HREF="../bips/kernel/env/help-1.html"><B>help/1</B></A><A NAME="@default96"></A> gives
help about specific built-in predicates.<BR>
<BR>
<A NAME="toc10"></A>
<H3 CLASS="subsection"><A NAME="htoc22">3.5.2</A>&nbsp;&nbsp;Interacting with the top level loop</H3>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> prompt <TT>[eclipse 1]:</TT> indicates that ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
is at the top level
and the opened module is <TT>eclipse</TT>.
The <EM>top level loop</EM><A NAME="@default97"></A> is a procedure which repetitively
prompts the user for a query, executes it and reports its
result, i.e., either the answer variable bindings or the
failure message.
There is always exactly one module opened in the top level
and its name is printed in the prompt.
From this point it is possible to enter ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goals, e.g., to
pose queries, to enter an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> program from the keyboard
or to compile a program from a file.
Goals are entered after the prompt and are terminated by fullstop and
newline.<BR>
<BR>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> system may be exited by typing CTRL-D (UNIX) or
CTRL-Z + RETURN (Windows) at the top level prompt,
<A NAME="@default98"></A>
or by calling either the <A HREF="../bips/kernel/opsys/halt-0.html"><B>halt/0</B></A><A NAME="@default99"></A>
or the <A HREF="../bips/kernel/opsys/exit-1.html"><B>exit/1</B></A><A NAME="@default100"></A> predicates.<BR>
<BR>
<A NAME="toc11"></A>
<H3 CLASS="subsection"><A NAME="htoc23">3.5.3</A>&nbsp;&nbsp;Compiling a program</H3>
The square brackets <TT>[</TT><I><FONT COLOR=maroon>...</FONT></I><TT>]</TT> or the
<A HREF="../bips/kernel/compiler/compile-1.html"><B>compile/1</B></A><A NAME="@default101"></A> predicate are used
to compile ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> source from a file.
If the goal
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
compile(myfile).
</PRE></BLOCKQUOTE>
or the short-hand notation
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
[myfile].
</PRE></BLOCKQUOTE>
is called, either as a query at the top level or within another goal,
the system looks for the file <TT>myfile</TT> or for a file called
<TT>myfile.pl</TT> or <TT>myfile.ecl</TT> and compiles it.
The short-hand notation may also be used to compile several files in
sequence:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
[ file_1, file_2, ..., file_n ]
</PRE></BLOCKQUOTE>
The <A HREF="../bips/kernel/compiler/compile-2.html"><B>compile/2</B></A><A NAME="@default102"></A> predicate may be
used to compile a file or list of
files into a module specified in the second argument.<BR>
<BR>
If a file has been modified since it was compiled, it may be recompiled by
invoking the <A HREF="../bips/kernel/env/make-0.html"><B>make/0</B></A><A NAME="@default103"></A> predicate.
This recompiles any files which have become out-of-date.<BR>
<BR>
For more information on program compilation and the compiler, please see
chapter <A HREF="umsroot028.html#chapcompiler">6</A>.<BR>
<BR>
<A NAME="toc12"></A>
<H3 CLASS="subsection"><A NAME="htoc24">3.5.4</A>&nbsp;&nbsp;Entering a program from the terminal</H3>
Programs can be entered directly from the terminal, as well as being read
from files.
To do this, simply compile the special file <TT>user</TT>.
That is, <TT>[user].</TT> or <TT>compile(user).</TT> at a top level
prompt.
The system then displays the compiler prompt (which is a blank by default)
and waits for a sequence of clauses.
Each of the clauses is terminated by a fullstop.<A NAME="@default104"></A><A NAME="@default105"></A>
(If the fullstop is omitted the system just sits
waiting, because it supposes the clause is not terminated.
If you omit the fullstop by accident simply type it in on the following line,
and then proceed to type in the program clauses, each followed by a fullstop and
carriage return.)
To return to the top level prompt,
type CTRL-D (UNIX), CTRL-Z + RETURN (Windows) or enter the atom
<TT>end_of_file</TT> followed by fullstop and RETURN.<BR>
<BR>
For example:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
[eclipse 1]: [user].
source_processor.eco loaded in 0.01 seconds
...
ecl_compiler.eco loaded in 0.23 seconds
 father(abraham, isaac).
 father(isaac, jacob).
 father(jacob, joseph).
 ancestor(X, Y) :- father(X, Y).
 ancestor(X, Y) :- ancestor(X, Z), ancestor(Z, Y).
 ^D
 tty        compiled 420 bytes in 0.01 seconds

Yes (0.24s cpu)
[eclipse 2]:
</PRE></BLOCKQUOTE>
The two predicates <B>father/2</B> and <B>ancestor/2</B> are now
compiled
and can be used.<BR>
<BR>
<A NAME="toc13"></A>
<H3 CLASS="subsection"><A NAME="htoc25">3.5.5</A>&nbsp;&nbsp;Executing a query</H3>
Once a set of clauses has been compiled,
it may be queried in the usual Prolog manner.
<A NAME="@default106"></A>
If there are uninstantiated variables<A NAME="@default107"></A> in the query,
the system will attempt to find an instantiation of them which will
satisfy the query, and if successful it will
display one such instantiation.
If potentially there is another solution, the top level 
will then wait for a further instruction: either a <CODE>&lt;CR&gt;</CODE>
(&#8220;newline&#8221; or &#8220;return&#8221;) or a semi-colon '<B>;</B>'.
A return will end the query successfully.
A semi-colon will initiate backtracking<A NAME="@default108"></A>
in an attempt to find another solution to the query.
Note that it is not necessary to type a new line after the semicolon
&mdash; one keystroke is enough.
When the top level loop can detect
that there are no further solutions, it does not wait for the semicolon
or newline, but it displays directly the next prompt.
For example in a query on
a family database:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
[eclipse 3]: father(X, Y).

X = abraham
Y = isaac
Yes (0.00s cpu, solution 1, maybe more) ? ;            (user types ';')

X = isaac
Y = jacob
Yes (0.00s cpu, solution 2)
[eclipse 4]:
</PRE></BLOCKQUOTE>
Queries may be extended over more than one line. When this is done the prompt
changes to a tabulation character, i.e., the input is indented to
indicate that the query is not yet completed.
The fullstop marks the end of the input.<BR>
<BR>
<A NAME="toc14"></A>
<H3 CLASS="subsection"><A NAME="htoc26">3.5.6</A>&nbsp;&nbsp;Interrupting the execution<A NAME="@default109"></A></H3>
If a program is executing, it may be interrupted by
typing <TT>CTRL-C</TT> (interrupt in the UNIX environment).
This will invoke the corresponding interrupt handler
(see section <A HREF="umsroot073.html#sectinterrupts">13.3</A>).
By default, the system prints a menu offering some alternatives:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
^C
interruption: type a, b, c, e, or h for help : ? h            (user types 'h')
help
 a : abort
 b : break level
 c : continue
 e : exit
 h : help


interruption: type a, b, c, e, or h for help : ?
</PRE></BLOCKQUOTE>
The <TT>a</TT> option returns to the toplevel, <TT>b</TT> starts a nested
toplevel,
<TT>c</TT> continues the interrupted execution, and <TT>e</TT> is an
emergency
exit
of the whole ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session. If the debugger is running, an additional
option <TT>d</TT> is displayed: it switches the debugger to creep mode.<BR>
<BR>
The execution of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> may be suspended by typing <TT>CTRL-Z</TT>
(suspend) or by calling <A HREF="../bips/kernel/opsys/pause-0.html"><B>pause/0</B></A><A NAME="@default110"></A>.
This will suspend the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process and return the UNIX prompt.
Entering the shell command <TT>fg</TT> will return to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.
Note that this feature may not be available on all systems.<BR>
<BR>
<A NAME="toc15"></A>
<H3 CLASS="subsection"><A NAME="htoc27">3.5.7</A>&nbsp;&nbsp;Debugging a program</H3>
Please see the chapters on debugging in the tutorial and user manuals for
more details. The tutorial chapter covers the TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> debugging in a
tutorial style tour, and the user manual chapter covers
 debugging in
general and the command-line debugger in particular.<BR>
<BR>
<A NAME="toc16"></A>
<H3 CLASS="subsection"><A NAME="htoc28">3.5.8</A>&nbsp;&nbsp;The history mechanism<A NAME="@default111"></A></H3>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> toplevel loop provides a simple history mechanism which allows
the examination and repetition of previous queries.
The history list is printed with the command <TT>h</TT>.
A previous query is invoked by typing either its absolute number or its
relative negative offset from the current query number (i.e., &ndash;1 will
execute the previous query).
The current query number is displayed in the toplevel prompt.<BR>
<BR>
The history is initialized from the file <TT>.eclipse_history</TT><A NAME="@default112"></A>
in the current directory or in the home directory.
This file contains the history goals, each ended by a fullstop.
The current history can be written using the predicate
<A HREF="../bips/lib/toplevel/write_history-0.html"><B>write_history/0</B></A><A NAME="@default113"></A> from the
<TT>util</TT> library.<BR>
<BR>
<A NAME="toc17"></A>
<H3 CLASS="subsection"><A NAME="htoc29">3.5.9</A>&nbsp;&nbsp;Getting help<A NAME="@default114"></A></H3>
Detailed documentation about all the predicates in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> libraries
can be obtained online through the help facility.
It has two modes of operation.
First, when a fragment of a built-in name is specified, a list of short
descriptions of all built-ins whose name contains the specified string
is printed.
For example,
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
:- help(write).
</PRE></BLOCKQUOTE>
will print one-line descriptions about <B>write/1</B>,
<B>writeclause/2</B>, etc.
When a unique specification is given, the full description of the
specified built-in is displayed, e.g., in
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
:- help(write/1).
</PRE></BLOCKQUOTE>
<HR>
<A HREF="umsroot012.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot008.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot014.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
